home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / tools / czesc_3 / remindme / remindme.doc < prev   
Text File  |  1994-09-11  |  13KB  |  327 lines
  1. *****************************************************************************
  2. *                                                                           *
  3. *                             Documentation for                             *
  4. *                                                                           *
  5. *                            -- RemindMe V1.0 --                            *
  6. *                                                                           *
  7. *                     Copyright © 1994 Marcus Stratmann                     *
  8. *                                                                           *
  9. *****************************************************************************
  10.  
  11.  
  12. SHORT DESCRIPTION
  13.  
  14.   RemindMe is a simple events reminder. It reads the events from a file
  15.   and checks if the user should be notified. Weekly, monthly, yearly and
  16.   unique events are possible. 
  17.  
  18.  
  19. CONTENTS
  20.  
  21.   The RemindMe package includes the following files:
  22.  
  23.   .Product-Info    the product description
  24.   RemindDates      a sample events file
  25.   RemindMe         the main program
  26.   RemindMe.doc     the documentation
  27.  
  28.  
  29. DISTRIBUTION
  30.  
  31.   RemindMe is FREEWARE. 
  32.   This  program may be freely distributed as long as all files of the
  33.   package remain unchanged and are included with the distribution.
  34.   Any commercial distribution of this package without the prior written
  35.   consent of the author (Marcus Stratmann) is expressly prohibited.
  36.   Copyright © 1994 by Marcus Stratmann
  37.  
  38.  
  39. REQUIREMENTS
  40.  
  41.   This program should run on any AMIGA. If it doesn't: please tell me!
  42.  
  43.  
  44. INSTALLATION
  45.  
  46.   Copy RemindMe into your C: directory or any other directory which is in
  47.   your search path. Copy the file RemindDates into your S: directory and
  48.   enter your own events. Include RemindMe in your startup-sequence. When
  49.   RemindMe is called, the current date should be set correctly, so you
  50.   better call SetClock before. The lines in your startup-sequence may look
  51.   like this:
  52.  
  53.     ...
  54.     SetClock load
  55.     RemindMe
  56.     ...
  57.  
  58.  
  59. FORMAT OF THE EVENTS FILE
  60.  
  61.   Your personal events are described in the file S:RemindDates.
  62.   Each line contains the description of one event.
  63.   Comments start with a semicolon (;) in the FIRST row of a line. The
  64.   whole line is considered as a comment and is ignored.
  65.   You can use one of the following formats for each event:
  66.  
  67.     WEEKLY  weekday  [WARN warndays] MESSAGE event-message
  68.     MONTHLY monthday [WARN warndays] MESSAGE event-message
  69.     YEARLY  yearday  [WARN warndays] MESSAGE event-message
  70.     UNIQUE  date     [WARN warndays] MESSAGE event-message
  71.  
  72.   For specification of the header use the format
  73.  
  74.     HEADER header-message
  75.  
  76.   Statements in [] are optional and can be omitted.
  77.   
  78.   RemindMe doesn't distinguish between uper and lower case. So "WEEKLY"
  79.   is the same as "weekly" or "WeEkLy".
  80.  
  81.   You can use some special codes for your header- and event-messages.
  82.   These are indicated by a backslash "\" followed by a character.
  83.   Special codes are:
  84.     \e  escape character (ASCII 27)
  85.     \f  form feed (clears the screen)
  86.     \n  line feed (new line)
  87.     \t  vorizontal tab
  88.     \\  a backslash ("\")
  89.  
  90.   Description of the keywords and their parameters:
  91.  
  92.     HEADER header-message
  93.  
  94.       This defines the message RemindMe displays first when it notifies you
  95.       of your events. Everything in the line after the keyword HEADER is
  96.       considered as your header-message (except leading blanks).
  97.       If HEADER is specified more than once, RemindMe will take the last
  98.       header-message.
  99.       When there are no events to remind you of RemindMe doesn't display
  100.       the header-message.
  101.  
  102.     WARN warndays
  103.  
  104.       This is the number of days you want to be notified before the event
  105.       takes place. When the number of days until the event is less or equal
  106.       to the value of warndays RemindMe will display the message belonging
  107.       to the event. A value of zero for warndays means that RemindMe
  108.       only notifies you on the day of the event, not before.
  109.       If you specify a negativ number, RemindMe will take its absolute
  110.       value.
  111.       If WARN is omitted, RemindMe assumes a value of zero for warndays.
  112.  
  113.     MESSAGE event-message
  114.  
  115.       Everything in the line after the keyword MESSAGE is taken as the
  116.       event-message (except leading blanks). This is displayed together
  117.       with the date of and the number of days to the event.
  118.       The length of the message is limited to 80 characters.      
  119.  
  120.     WEEKLY weekday
  121.  
  122.       This defines a weekly event.
  123.       weekday should be replaced by one of the following:
  124.         MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
  125.       This is the weekday your weekly event is going to happen.
  126. *     NOTE: RemindMe always takes the next possible date which matches
  127.       the specification. E.g. if you say
  128.         WEEKLY MONDAY WARN 14 MESSAGE Monday again!
  129.       RemindMe will only remind you of the next monday and not of the
  130.       monday seven days later, though it is in the range of 14 warndays, 
  131.       too. This is also effective for MONTHLY and YEARLY.
  132.  
  133.     MONTHLY monthday
  134.  
  135.       This defines a monthly event.
  136.       Valid numbers for monthday are 1 to 31 and -1 TO -31.
  137.       A positive number stands for the corresponding day of the month.
  138.       If a negative number is specified, the days are counted from behind.
  139.       So -1 belongs to the last day of the month (not 0!) and in a month
  140.       with 30 days, -30 belongs to the first day of the month.
  141.       If a month doesn't have the required number of days, the next
  142.       matching month is taken.
  143.  
  144.     YEARLY yearday
  145.  
  146.       This defines a yearly event.
  147.       yearday is of the form day.month. where day and month are both
  148.       numbers. RemindMe checks if the date is valid.
  149.  
  150.     UNIQUE date
  151.  
  152.       This defines an event that takes place only once.
  153.       date is of the form day.month.year where day, month and year are
  154.       all numbers. Don't forget the century when specifying the date;
  155.       1994 and 94 are different years! Again, the validity of the date
  156.       is checked.
  157.  
  158.  
  159. COMMAND-LINE OPTIONS
  160.  
  161.   The syntax for the RemindMe command line is given as:
  162.  
  163.     RemindMe [ALL] [TEST]
  164.  
  165.   The text in brackets ("[]") indicates an optional parameter.
  166.   Here's the meaning of the options:
  167.  
  168.   ALL
  169.  
  170.     Normally RemindMe will display only those events whose occurrence
  171.     lie in the specified warndays range. But when the option ALL is
  172.     given, RemindMe will display all events, even those whose occurrence
  173.     does not lie in the warndays range.
  174.     Use this to see which events you have entered in the events file 
  175.     S:RemindDates.
  176.  
  177.   TEST
  178.  
  179.     When reading the file S:RemindDates the program will not report any
  180.     errors or warnings. If you want to test, if your events file is ok,
  181.     use the TEST option. RemindMe will then report possible errors and
  182.     give you the corresponding line numbers.
  183.  
  184.  
  185. OUTPUT OF THE PROGRAM
  186.  
  187.   Let's have a look at the output RemindMe produces. I started the program
  188.   on 11-Oct-1994 from the command line with
  189.     RemindMe ALL TEST 
  190.   and with the sample events file of this this archiv in use.
  191.   Here's the output of the program:
  192.  
  193.     RemindMe V1.0, Copyright (c) 1994 Marcus Stratmann.
  194.  
  195.     Error   line 16: Illegal weekday
  196.     Warning line 18: Obsolete date
  197.     1 error(s), 1 warning(s).
  198.  
  199.     don't forget:
  200.        tomorrow (Mo, 12-Sep-1994): Oh no, monday again!
  201.     in   4 days (Th, 15-Sep-1994): This is the 15th day of the month
  202.     in  19 days (Fr, 30-Sep-1994): Month is over! Any money left?
  203.     in  20 days (Sa,  1-Oct-1994): This is the first day of the next month ...
  204.     in  50 days (Mo, 31-Oct-1994): This is the 31st day of the month
  205.     in 104 days (Sa, 24-Dec-1994): Christmas! Don't forget the presents!
  206.     in 386 days (Mo,  2-Oct-1995): This is a monday, too.
  207.     in 536 days (Th, 29-Feb-1996): Intercalary day
  208.  
  209.   In the first line you find the program name, version and copyright note.
  210.   This is only output when the TEST option is active.
  211.  
  212.   The next lines give you a summary of the errors and warnings. As you can
  213.   see, in line 16 an illegal weekday was specified (moonday instead of
  214.   monday) which gives you an error message. In line 18 of the events file
  215.   the date 01.03.1966 was used which is more than 28 years over. This
  216.   results in the warning "obsolete date".
  217. * NOTE: RemindMe never changes the events file! That means it doesn't
  218.   discard obsolete events. This prevents data losses due to a wrong current
  219.   date set.
  220.   The errors and warnings summary is displayed only when the TEST option
  221.   is active.
  222.  
  223.   The next part of the output gives a summary of the events. As I used the
  224.   ALL options, all events from the events file are displayed. Events which
  225.   lie in the past are not shown.
  226.   In the first line of this part the header-message is shown. If you don't
  227.   specify a header-message, none is shown (you guessed that, hm? :-)
  228.   For each event you get:
  229.   - the days until the occurence of the event (0 days is replaced by
  230.     "today", 1 day by "tomorrow")
  231.   - the date of the event in the form <weekday, day-month-year>
  232.   - the message for the event
  233.   This part of the output is shown only when there are any events to be
  234.   displayed.
  235.  
  236.  
  237. ERRORS, WARNINGS AND RETURN CODES
  238.  
  239.   There are two differnt kind of error: "hard" errors and "soft" errors.
  240.   Soft errors occur when RemindMe reads the events file and finds a
  241.   syntactic error in it. In this case it skips to the next line. If the
  242.   TEST option is active, you get an error message indicating the line
  243.   number and the cause of the error. Soft errors don't interrupt the
  244.   program.
  245.   All other errors are hard errors. These result in the termination of the
  246.   program, as something really important went wrong. Hard errors are shown
  247.   even if the TEST option is not set.
  248.   Warnings inform you that something unexpected has happen, which doesn't
  249.   seriously affect the execution of the program. As in the case of soft 
  250.   errors, warnings are displayed only if the TEST option is active.
  251.  
  252.   Hard errors:
  253.     File not found
  254.       The events file S:RemindDates wasn't found.
  255.     Can't examine file
  256.       The progaram couldn't examine the length of the events file.
  257.     This should be a file, not a directory
  258.       S:RemindDates is a directory, not a file.
  259.     File is empty
  260.       The file S:RemindDates is empty.
  261.     No Memory
  262.       There is not enough free memory for the program.
  263.     Can't open file
  264.       The program can't open the events file.
  265.     Error reading file
  266.       An error occurred while reading from the file.
  267.     Date seems to be wrong
  268.       The current date seems to be wrong. You get this message when the
  269.       year is set to less then 1994.
  270.  
  271.   Soft errors:
  272.     Illegal weekday
  273.       The weekday after the keyword WEEKLY is wrong. Legal weekdays are
  274.       MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
  275.     Illegal day
  276.       The day after the keyword MONTHLY is wrong. Valid numbers are 
  277.       1 to 31 and -1 TO -31.
  278.     Illegal date
  279.       The date after one of the keywords YEARLY or UNIQUE is wrong.
  280.       The format is day.month. for YEARLY and day.month.year for UNIQUE.
  281.       Maybe you forgot a "." or you stated a date which doesn't exist.
  282.       Remember that all parts of the date consist of numbers, so don't
  283.       use something like "oct" for the month.
  284.     MESSAGE expected
  285.       The program didn't find the keyword MESSAGE. Every event needs a
  286.       message (which might be empty) following the MESSAGE keyword.
  287.     Keyword expected
  288.       The program expected one of the keywords WEEKY, MONTHLY, YEARLY,
  289.       UNIQUE, HEADER. This might be a sequel of an error in the line before.
  290.       To protect you from such consequences you should use only one line
  291.       for each event.
  292.     Illegal number
  293.       The program unsuccessfully tried to read a number (e.g. the day of a
  294.       date).
  295.     String too long
  296.       The length of a string the program can read is limited to 100 char-
  297.       acters. You stated a string (e.g. a date) which is longer than 100
  298.       characters.
  299.  
  300.   Warnings:
  301.     Obsolete date
  302.       The date stated after UNIQUE is obsolete. You should erase this line
  303.       from the events file.
  304.     Message truncated
  305.       The length of messages is limited to 80 characters. If your message
  306.       is longer, the program will truncate it.
  307.  
  308.   Return codes:
  309.     This is what the program gives back to the operating system when it
  310.     quits. The code for warnings is 5, for soft errors 10 and for hard
  311.     errors 20 (except for 'wrong date', which gives back 10). The highest
  312.     error code which occures is given back as the return code.
  313.  
  314.  
  315. THE AUTHOR
  316.  
  317.   Send bug reports, suggestions, money, food :-) or other nice things to:
  318.  
  319.   Marcus Stratmann
  320.   Böttcherstr. 13
  321.   46244 Kirchhellen
  322.   Germany
  323.  
  324.   E-Mail: uste01@unidozr.hrz.uni-dortmund.de (until March 1995)
  325.  
  326.   "Der Tag würde mehr Spaß machen, wenn er später anfinge."
  327.